home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_groff.idb / usr / freeware / info / groff-3.z / groff-3
Text File  |  2002-04-08  |  51KB  |  1,447 lines
  1. This is groff, produced by makeinfo version 4.0 from groff.texinfo.
  2.  
  3. INFO-DIR-SECTION Miscellaneous
  4. START-INFO-DIR-ENTRY
  5. * Groff: (groff).  The GNU troff document formatting system.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This Info file documents GNU troff version 1.16.
  9.  
  10.    Published by the Free Software Foundation 59 Temple Place, Suite 330
  11. Boston, MA  02111-1307  USA
  12.  
  13.    Copyright (C) 1994-2000 Free Software Foundation, Inc.
  14.  
  15.    Permission is granted to make and distribute verbatim copies of this
  16. manual provided the copyright notice and this permission notice are
  17. preserved on all copies.
  18.  
  19.    Permission is granted to copy and distribute modified versions of
  20. this manual under the conditions for verbatim copying, provided that the
  21. entire resulting derived work is distributed under the terms of a
  22. permission notice identical to this one.
  23.  
  24.    Permission is granted to copy and distribute translations of this
  25. manual into another language, under the above conditions for modified
  26. versions, except that this permission notice may be stated in a
  27. translation approved by the Foundation.
  28.  
  29.    Permission is granted to copy and distribute modified versions of
  30. this manual under the conditions for verbatim copying, provided also
  31. that the section entitled "GNU General Public License" is included
  32. exactly as in the original, and provided that the entire resulting
  33. derived work is distributed under the terms of a permission notice
  34. identical to this one.
  35.  
  36.    Permission is granted to copy and distribute translations of this
  37. manual into another language, under the above conditions for modified
  38. versions, except that the section entitled "GNU General Public License"
  39. may be included in a translation approved by the Free Software
  40. Foundation instead of in the original English.
  41.  
  42. 
  43. File: groff,  Node: Setting Registers,  Next: Interpolating Registers,  Prev: Registers,  Up: Registers
  44.  
  45. Setting Registers
  46. -----------------
  47.  
  48.    Define or set registers using the `nr' request or the `\R' escape.
  49.  
  50.  - Request: .nr ident value
  51.  - Escape: \R'IDENT VALUE'
  52.      Set number register IDENT to VALUE.  If IDENT doesn't exist,
  53.      `gtroff' creates it.
  54.  
  55.      The argument to `\R' usually has to be enclosed in quotes.  *Note
  56.      Escapes::, for details on parameter delimiting characters.
  57.  
  58.    For example, the following two lines are equivalent:
  59.  
  60.  
  61.      .nr a 1
  62.      \R'a 1'
  63.  
  64.    Both `nr' and `\R' have two additional special forms to increment or
  65. decrement a register.
  66.  
  67.  - Request: .nr ident +value
  68.  - Request: .nr ident -value
  69.  - Escape: \R'IDENT +VALUE'
  70.  - Escape: \R'IDENT -VALUE'
  71.      Increment (decrement) register IDENT by VALUE.
  72.  
  73.  
  74.           .nr a 1
  75.           .nr a +1
  76.           \na
  77.               => 2
  78.  
  79.      To assign the negated value of a register to another register,
  80.      some care must be taken to get the desired result:
  81.  
  82.  
  83.           .nr a 7
  84.           .nr b 3
  85.           .nr a -\nb
  86.           \na
  87.               => 4
  88.           .nr a (-\nb)
  89.           \na
  90.               => -3
  91.  
  92.      The surrounding parentheses prevent the interpretation of the
  93.      minus sign as a decrementing operator.  An alternative is to start
  94.      the assignment with a `0':
  95.  
  96.  
  97.           .nr a 7
  98.           .nr b -3
  99.           .nr a \nb
  100.           \na
  101.               => 4
  102.           .nr a 0\nb
  103.           \na
  104.               => -3
  105.  
  106.  
  107.  - Request: .rr ident
  108.      Remove number register IDENT.  If IDENT doesn't exist, the request
  109.      is ignored.
  110.  
  111.  - Request: .rnn ident1 ident2
  112.      Rename number register IDENT1 to IDENT2.  If either IDENT1 or
  113.      IDENT2 doesn't exist, the request is ignored.
  114.  
  115.  - Request: .aln ident1 ident2
  116.      Create an alias IDENT1 for a number register IDENT2.  The new name
  117.      and the old name are exactly equivalent.  If IDENT1 is undefined,
  118.      a warning of type `reg' is generated, and the request is ignored.
  119.      *Note Debugging::, for information about warnings.
  120.  
  121. 
  122. File: groff,  Node: Interpolating Registers,  Next: Auto-increment,  Prev: Setting Registers,  Up: Registers
  123.  
  124. Interpolating Registers
  125. -----------------------
  126.  
  127.    Numeric registers can be accessed via the `\n' escape.
  128.  
  129.  - Escape: \nI
  130.  - Escape: \n(ID
  131.  - Escape: \n[IDENT]
  132.      Interpolate number register with name IDENT (one-character name I,
  133.      two-character name ID).  This means that the value of the register
  134.      is expanded in-place while `gtroff' is parsing the input line.
  135.      Nested assignments (also called indirect assignments) are possible.
  136.  
  137.  
  138.           .nr a 5
  139.           .nr as \na+\na
  140.           \n(as
  141.               => 10
  142.  
  143.  
  144.           .nr a1 5
  145.           .nr ab 6
  146.           .ds str b
  147.           .ds num 1
  148.           \n[a\n[num]]
  149.               => 5
  150.           \n[a\*[str]]
  151.               => 6
  152.  
  153.  
  154. 
  155. File: groff,  Node: Auto-increment,  Next: Assigning Formats,  Prev: Interpolating Registers,  Up: Registers
  156.  
  157. Auto-increment
  158. --------------
  159.  
  160.    Number registers can also be auto-incremented and auto-decremented.
  161. The increment or decrement value can be specified with a third argument
  162. to the `nr' request or `\R' escape.
  163.  
  164.  - Request: .nr ident value incr
  165.      Set number register IDENT to VALUE; the increment for
  166.      auto-incrementing is set to INCR.  Note that the `\R' escape
  167.      doesn't support this notation.
  168.  
  169.    To activate auto-incrementing, the escape `\n' has a special syntax
  170. form.
  171.  
  172.  - Escape: \n+I
  173.  - Escape: \n-I
  174.  - Escape: \n(+ID
  175.  - Escape: \n(-ID
  176.  - Escape: \n+(ID
  177.  - Escape: \n-(ID
  178.  - Escape: \n[+IDENT]
  179.  - Escape: \n[-IDENT]
  180.  - Escape: \n+[IDENT]
  181.  - Escape: \n-[IDENT]
  182.      Before interpolating, increment or decrement IDENT (one-character
  183.      name I, two-character name ID) by the auto-increment value as
  184.      specified with the `nr' request (or the `\R' escape).  If no
  185.      auto-increment value has been specified, these syntax forms are
  186.      identical to `\n'.
  187.  
  188.    For example,
  189.  
  190.  
  191.      .nr a 0 1
  192.      .nr xx 0 5
  193.      .nr foo 0 -2
  194.      \n+a, \n+a, \n+a, \n+a, \n+a
  195.      .br
  196.      \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
  197.      .br
  198.      \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
  199.  
  200. produces
  201.  
  202.  
  203.      1, 2, 3, 4, 5
  204.      -5, -10, -15, -20, -25
  205.      -2, -4, -6, -8, -10
  206.  
  207.    To change the increment value without changing the value of a
  208. register (A in the example), the following can be used:
  209.  
  210.  
  211.      .nr a \na 10
  212.  
  213. 
  214. File: groff,  Node: Assigning Formats,  Next: Built-in Registers,  Prev: Auto-increment,  Up: Registers
  215.  
  216. Assigning Formats
  217. -----------------
  218.  
  219.    When a register is used in the text of an input file (as opposed to
  220. part of an expression), it is textually replaced (or interpolated) with
  221. a representation of that number.  This output format can be changed to
  222. a variety of formats (numbers, Roman numerals, etc.).  This is done
  223. using the `af' request.
  224.  
  225.  - Request: .af ident format
  226.      Change the output format of a number register.  The first argument
  227.      IDENT is the name of the number register to be changed, and the
  228.      second argument FORMAT is the output format.  The following output
  229.      formats are available:
  230.  
  231.     `1'
  232.           Decimal arabic numbers.  This is the default format: 0, 1, 2,
  233.           3, ....
  234.  
  235.     `0...0'
  236.           Decimal numbers with as many digits as specified.  So, `00'
  237.           would result in printing numbers as 01, 02, 03, ....
  238.  
  239.           In fact, any digit instead of zero will do; `gtroff' only
  240.           counts how many digits are specified.  As a consequence,
  241.           `af''s default format `1' could be specified as `0' also (and
  242.           exactly this is returned by the `\g' escape, see below).
  243.  
  244.     `I'
  245.           Upper-case Roman numerals: 0, I, II, III, IV, ....
  246.  
  247.     `i'
  248.           Lower-case Roman numerals: 0, i, ii, iii, iv, ....
  249.  
  250.     `A'
  251.           Upper-case letters: 0, A, B, C, ..., Z, AA, AB, ....
  252.  
  253.     `a'
  254.           Lower-case letters: 0, a, b, c, ..., z, aa, ab, ....
  255.  
  256.      Omitting the number register format causes a warning of type
  257.      `missing'.  *Note Debugging::, for more details.  Specifying a
  258.      nonexistent format causes an error.
  259.  
  260.      The following example produces `10, X, j, 010':
  261.  
  262.  
  263.           .nr a 10
  264.           .af a 1           \" the default format
  265.           \na,
  266.           .af a I
  267.           \na,
  268.           .af a a
  269.           \na,
  270.           .af a 001
  271.           \na
  272.  
  273.      The largest number representable for the `i' and `I' formats is
  274.      39999 (or -39999); UNIX `troff' uses `z' and `w' to represent
  275.      10000 and 5000 in Roman numerals, and so does `gtroff'.
  276.      Currently, the correct glyphs of Roman numeral five thousand and
  277.      Roman numeral ten thousand (Unicode code points `U+2182' and
  278.      `U+2181', respectively) are not available.
  279.  
  280.      If IDENT doesn't exist, it is created.
  281.  
  282.      Changing the output format of a read-only register causes an
  283.      error.  It is necessary to first copy the register's value to a
  284.      writeable register, then apply the `af' request to this other
  285.      register.
  286.  
  287.  - Escape: \gI
  288.  - Escape: \g(ID
  289.  - Escape: \g[IDENT]
  290.      Return the current format of the specified register IDENT
  291.      (one-character name I, two-character name ID).  For example, `\ga'
  292.      after the previous example would produce the string `000'.  If the
  293.      register hasn't been defined yet, nothing is returned.
  294.  
  295. 
  296. File: groff,  Node: Built-in Registers,  Prev: Assigning Formats,  Up: Registers
  297.  
  298. Built-in Registers
  299. ------------------
  300.  
  301.    The following lists some built-in registers which are not described
  302. elsewhere in this manual.  Any register which begins with a `.' is
  303. read-only.  A complete listing of all built-in registers can be found in
  304. *Note Register Index::.
  305.  
  306. `.H'
  307.      Horizontal resolution in basic units.
  308.  
  309. `.V'
  310.      Vertical resolution in basic units.
  311.  
  312. `dw'
  313.      Day of the week (1-7).
  314.  
  315. `dy'
  316.      Day of the month (1-31).
  317.  
  318. `mo'
  319.      Current month (1-12).
  320.  
  321. `year'
  322.      The current year.
  323.  
  324. `yr'
  325.      The current year minus 1900.  Unfortunately, the documentation of
  326.      UNIX Version 7's `troff' had a year 2000 bug: It incorrectly
  327.      claimed that `yr' contains the last two digits of the year.  That
  328.      claim has never been true of either traditional `troff' or GNU
  329.      `troff'.  Old `troff' input that looks like this:
  330.  
  331.  
  332.           '\" The following line stopped working after 1999
  333.           This document was formatted in 19\n(yr.
  334.  
  335.      can be corrected as follows:
  336.  
  337.  
  338.           This document was formatted in \n[year].
  339.  
  340.      or, to be portable to older `troff' versions, as follows:
  341.  
  342.  
  343.           .nr y4 1900+\n(yr
  344.           This document was formatted in \n(y4.
  345.  
  346. `.c'
  347. `c.'
  348.      The current _input_ line number.  Register `.c' is read-only,
  349.      whereas `c.' (a `gtroff' extension) is writable also, affecting
  350.      both `.c' and `c.'.
  351.  
  352. `ln'
  353.      The current _output_ line number after a call to the `nm' request
  354.      to activate line numbering.
  355.  
  356.      *Note Miscellaneous::, for more information about line numbering.
  357.  
  358. `.x'
  359.      The major version number.  For example, if the version number
  360.      is 1.03 then `.x' contains `1'.
  361.  
  362. `.y'
  363.      The minor version number.  For example, if the version number
  364.      is 1.03 then `.y' contains `03'.
  365.  
  366. `.Y'
  367.      The revision number of `groff'.
  368.  
  369. `.g'
  370.      Always 1.  Macros should use this to determine whether they are
  371.      running under GNU `troff'.
  372.  
  373. `.A'
  374.      If the command line option `-a' is used to produce an ASCII
  375.      approximation of the output, this is set to 1, zero otherwise.
  376.      *Note Groff Options::.
  377.  
  378. `.P'
  379.      This register is set to 1 (and to 0 otherwise) if the current page
  380.      is actually being printed, i.e., if the `-o' option is being used
  381.      to only print selected pages.  *Note Groff Options::, for more
  382.      information.
  383.  
  384. `.T'
  385.      If `gtroff' is called with the `-T' command line option, the
  386.      number register `.T' is set to 1, and zero otherwise.  *Note Groff
  387.      Options::.
  388.  
  389.      Additionally, `gtroff' predefines a single read-write string
  390.      register `.T' which contains the current output device (for
  391.      example, `latin1' or `ps').
  392.  
  393. 
  394. File: groff,  Node: Manipulating Filling and Adjusting,  Next: Manipulating Hyphenation,  Prev: Registers,  Up: gtroff Reference
  395.  
  396. Manipulating Filling and Adjusting
  397. ==================================
  398.  
  399.    Various ways of causing "breaks" were given in *Note Implicit Line
  400. Breaks::.  The `br' request likewise causes a break.  Several other
  401. requests also cause breaks, but implicitly.  These are `bp', `ce',
  402. `cf', `fi', `fl', `in', `nf', `rj', `sp', `ti', and `trf'.
  403.  
  404.  - Request: .br
  405.      Break the current line, i.e., the input collected so far is emitted
  406.      without adjustment.
  407.  
  408.      If the no-break control character is used, `gtroff' suppresses the
  409.      break:
  410.  
  411.  
  412.           a
  413.           'br
  414.           b
  415.               => a b
  416.  
  417.  
  418.    Initially, `gtroff' fills and adjusts text to both margins.  Filling
  419. can be disabled via the `nf' request and re-enabled with the `fi'
  420. request.
  421.  
  422.  - Request: .fi
  423.  - Register: \n[.u]
  424.      Activate fill mode (which is the default).  This request implicitly
  425.      enables adjusting; it also inserts a break in the text currently
  426.      being filled.  The read-only number register `.u' is set to 1.
  427.  
  428.      The fill mode status is associated with the current environment
  429.      (*note Environments::).
  430.  
  431.  - Request: .nf
  432.      Activate no-fill mode.  Input lines are output as-is, retaining
  433.      line breaks and ignoring the current line length.  This command
  434.      implicitly disables adjusting; it also causes a break.  The number
  435.      register `.u' is set to 0.
  436.  
  437.      The fill mode status is associated with the current environment
  438.      (*note Environments::).
  439.  
  440.  - Request: .ad [mode]
  441.  - Register: \n[.j]
  442.      Set adjusting mode.
  443.  
  444.      Activation and deactivation of adjusting is done implicitly with
  445.      calls to the `fi' or `nf' requests.
  446.  
  447.      MODE can have one of the following values:
  448.  
  449.     `l'
  450.           Adjust text to the left margin.  This produces what is
  451.           traditionally called ragged-right text.
  452.  
  453.     `r'
  454.           Adjust text to the right margin, producing ragged-left text.
  455.  
  456.     `c'
  457.           Center filled text.  This is different to the `ce' request
  458.           which only centers text without filling.
  459.  
  460.     `b'
  461.     `n'
  462.           Justify to both margins.  This is the default used by
  463.           `gtroff'.
  464.  
  465.      With no argument, `gtroff' adjusts lines in the same way it did
  466.      before adjusting was deactivated (with a call to `na', for
  467.      example).
  468.  
  469.  
  470.           text
  471.           .ad r
  472.           text
  473.           .ad c
  474.           text
  475.           .na
  476.           text
  477.           .ad  \" back to centering
  478.           text
  479.  
  480.      The current adjustment mode is available in the read-only number
  481.      register `.j'; it can be stored and subsequently used to set
  482.      adjustment.
  483.  
  484.      The adjustment mode status is associated with the current
  485.      environment (*note Environments::).
  486.  
  487.  - Request: .na
  488.      Disable adjusting.  This request won't change the current
  489.      adjustment mode: A subsequent call to `ad' uses the previous
  490.      adjustment setting.
  491.  
  492.      The adjustment mode status is associated with the current
  493.      environment (*note Environments::).
  494.  
  495.  - Escape: \p
  496.      Adjust the current line and cause a break.
  497.  
  498.      In most cases this produces very ugly results, since `gtroff'
  499.      doesn't have a sophisticated paragraph building algorithm (as TeX
  500.      have, for example); instead, `gtroff' fills and adjusts a paragraph
  501.      line by line:
  502.  
  503.  
  504.             This is an uninteresting sentence.
  505.             This is an uninteresting sentence.\p
  506.             This is an uninteresting sentence.
  507.  
  508.      is formatted as
  509.  
  510.  
  511.             This is  an uninteresting  sentence.   This  is an
  512.             uninteresting                            sentence.
  513.             This is an uninteresting sentence.
  514.  
  515.  
  516.  - Request: .ss word_space_size [sentence_space_size]
  517.  - Register: \n[.ss]
  518.  - Register: \n[.sss]
  519.      Change the minimum size of a space between filled words.  It takes
  520.      its units as one twelfth of the space width parameter for the
  521.      current font.  Initially both the WORD_SPACE_SIZE and
  522.      SENTENCE_SPACE_SIZE are 12.
  523.  
  524.      If two arguments are given to the `ss' request, the second
  525.      argument sets the sentence space size.  If the second argument is
  526.      not given, sentence space size is set to WORD_SPACE_SIZE.  The
  527.      sentence space size is used in two circumstances: If the end of a
  528.      sentence occurs at the end of a line in fill mode, then both an
  529.      inter-word space and a sentence space are added; if two spaces
  530.      follow the end of a sentence in the middle of a line, then the
  531.      second space is a sentence space.  If a second argument is never
  532.      given to the `ss' request, the behaviour of UNIX `troff' is the
  533.      same as that exhibited by GNU `troff'.  In GNU `troff', as in UNIX
  534.      `troff', a sentence should always be followed by either a newline
  535.      or two spaces.
  536.  
  537.      The read-only number registers `.ss' and `.sss' hold the values of
  538.      the parameters set by the first and second arguments of the `ss'
  539.      request.
  540.  
  541.      The word space and sentence space values are associated with the
  542.      current environment (*note Environments::).
  543.  
  544.      Contrary to traditional Unix `troff', this request is _not_
  545.      ignored if a tty output device is used; the given values are then
  546.      rounded down to a multiple of 12.
  547.  
  548.      The request is ignored if there is no parameter.
  549.  
  550.  - Request: .ce [nnn]
  551.  - Register: \n[.ce]
  552.      Center text.  While the `.ad c' request also centers text, it
  553.      fills the text as well.  `ce' does not fill the text it affects.
  554.      This request causes a break.
  555.  
  556.      The following example demonstrates the differences.  Here the
  557.      input:
  558.  
  559.  
  560.           .ll 4i
  561.           .ce 1000
  562.           This is a small text fragment which shows the differences
  563.           between the `.ce' and the `.ad c' request.
  564.           .ce 0
  565.           
  566.           .ad c
  567.           This is a small text fragment which shows the differences
  568.           between the `.ce' and the `.ad c' request.
  569.  
  570.      And here the result:
  571.  
  572.  
  573.             This is a small text fragment which
  574.                    shows the differences
  575.           between the `.ce' and the `.ad c' request.
  576.           
  577.             This is a small text fragment which
  578.           shows the differences between the `.ce'
  579.                   and the `.ad c' request.
  580.  
  581.      With no arguments, `ce' centers the next line of text.  NNN
  582.      specifies the number of lines to be centered.  If the argument is
  583.      zero or negative, centering is disabled.
  584.  
  585.      The basic length for centering text is the line length (as set
  586.      with the `ll' request) minus the indentation (as set with the `in'
  587.      request).  Temporary indentation is ignored.
  588.  
  589.      As can be seen in the previous example, it is a common idiom to
  590.      turn on centering for a large number of lines, and to turn off
  591.      centering after text to be centered.  This is useful for any
  592.      request which takes a number of lines as an argument.
  593.  
  594.      The `.ce' read-only number register contains the number of lines
  595.      remaining to be centered, as set by the `ce' request.
  596.  
  597.  - Request: .rj [nnn]
  598.  - Register: \n[.rj]
  599.      Justify unfilled text to the right margin.  Arguments are
  600.      identical to the `ce' request.  The `.rj' read-only number
  601.      register is the number of lines to be right-justified as set by
  602.      the `rj' request.  This request causes a break.
  603.  
  604. 
  605. File: groff,  Node: Manipulating Hyphenation,  Next: Manipulating Spacing,  Prev: Manipulating Filling and Adjusting,  Up: gtroff Reference
  606.  
  607. Manipulating Hyphenation
  608. ========================
  609.  
  610.    As discussed in *Note Hyphenation::, `gtroff' hyphenates words.
  611. There are a number of ways to influence hyphenation.
  612.  
  613.  - Request: .hy [mode]
  614.  - Register: \n[.hy]
  615.      Enable hyphenation.  The request has an optional numeric argument,
  616.      MODE, to restrict hyphenation if necessary:
  617.  
  618.     `1'
  619.           The default argument if MODE is omitted.  Hyphenate without
  620.           restrictions.  This is also the start-up value of `gtroff'.
  621.  
  622.     `2'
  623.           Do not hyphenate the last word on a page or column.
  624.  
  625.     `4'
  626.           Do not hyphenate the last two characters of a word.
  627.  
  628.     `8'
  629.           Do not hyphenate the first two characters of a word.
  630.  
  631.      Values in the previous table are additive.  For example, the
  632.      value 12 causes `gtroff' to neither hyphenate the last two nor the
  633.      first two characters of a word.
  634.  
  635.      The current hyphenation restrictions can be found in the read-only
  636.      number register `.hy'.
  637.  
  638.      The hyphenation mode is associated with the current environment
  639.      (*note Environments::).
  640.  
  641.  - Request: .nh
  642.      Disable hyphenation (i.e., set the hyphenation mode to zero).  Note
  643.      that the hyphenation mode of the last call to `hy' is not
  644.      remembered.
  645.  
  646.      The hyphenation mode is associated with the current environment
  647.      (*note Environments::).
  648.  
  649.  - Request: .hlm [nnn]
  650.  - Register: \n[.hlm]
  651.  - Register: \n[.hlc]
  652.      Set the maximum number of consecutive hyphenated lines to NNN.  If
  653.      this number is negative, there is no maximum.  The default value
  654.      is -1 if NNN is omitted.  This value is associated with the
  655.      current environment (*note Environments::).  Only lines output
  656.      from a given environment count towards the maximum associated with
  657.      that environment.  Hyphens resulting from `\%' are counted;
  658.      explicit hyphens are not.
  659.  
  660.      The current setting of `hlm' is available in the `.hlm' read-only
  661.      number register.  Also the number of immediately preceding
  662.      consecutive hyphenated lines are available in the read-only number
  663.      register `.hlc'.
  664.  
  665.  - Request: .hw word1 word2 ...
  666.      Define how WORD1, WORD2, etc. are to be hyphenated.  The words
  667.      must be given with hyphens at the hyphenation points.  For example:
  668.  
  669.  
  670.           .hw in-sa-lub-rious
  671.  
  672.      Besides the space character, any character whose hyphenation code
  673.      value is zero can be used to separate the arguments of `hw' (see
  674.      the documentation for the `hcode' request below for more
  675.      information).  In addition, this request can be used more than
  676.      once.
  677.  
  678.      Hyphenation exceptions specified with the `hw' request are
  679.      associated with the current hyphenation language; it causes an
  680.      error if there is no current hyphenation language.
  681.  
  682.      This request is ignored if there is no parameter.
  683.  
  684.      In old versions of `troff' there was a limited amount of space to
  685.      store such information; fortunately, with `gtroff', this is no
  686.      longer a restriction.
  687.  
  688.  - Escape: \%
  689.      To tell `gtroff' how to hyphenate words on the fly, use the `\%'
  690.      escape, also known as the "hyphenation character".  Preceding a
  691.      word with this character prevents it from being hyphenated;
  692.      putting it inside a word indicates to `gtroff' that the word may
  693.      be hyphenated at that point.  Note that this mechanism only
  694.      affects that one occurrence of the word; to change the hyphenation
  695.      of a word for the entire document, use the `hw' request.
  696.  
  697.  - Request: .hc [char]
  698.      Change the hyphenation character to CHAR.  This character then
  699.      works the same as the `\%' escape, and thus, no longer appears in
  700.      the output.  Without an argument, `hc' resets the hyphenation
  701.      character to be `\%' (the default) only.
  702.  
  703.      The hyphenation character is associated with the current
  704.      environment (*note Environments::).
  705.  
  706.  - Request: .hpf pattern_file
  707.      Read in a file of hyphenation patterns.  This file is searched for
  708.      in the same way as `NAME.tmac' (or `tmac.NAME') is searched for if
  709.      the `-mNAME' option is specified.
  710.  
  711.      It should have the same format as the argument to the `\patterns'
  712.      primitive in TeX (without using TeX's macro expansion); the
  713.      letters appearing in this file are interpreted as hyphenation
  714.      codes.  A `%' character in the patterns file introduces a comment
  715.      that continues to the end of the line.
  716.  
  717.      If no `hpf' request is specified (either in the document or in a
  718.      macro package), `gtroff' won't hyphenate at all.
  719.  
  720.      The set of hyphenation patterns is associated with the current
  721.      language set by the `hla' request.  The `hpf' request is usually
  722.      invoked by the `troffrc' or `troffrc-end' file; by default,
  723.      `troffrc' loads hyphenation patterns for American English (in file
  724.      `hyphen.us').
  725.  
  726.      Invoking `hpf' causes an error if there is no current hyphenation
  727.      language.
  728.  
  729.  - Request: .hcode c1 code1 c2 code2 ...
  730.      Set the hyphenation code of character C1 to CODE1, that of C2 to
  731.      CODE2, etc.  A hyphenation code must be a single input character
  732.      (not a special character) other than a digit or a space.
  733.      Initially each lower-case letter (`a'-`z') has its hyphenation set
  734.      to itself, and each upper-case letter (`A'-`Z') has a hyphenation
  735.      code which is the lower-case version of itself.
  736.  
  737.      This request is ignored if it has no parameter.
  738.  
  739.  - Request: .hym [length]
  740.  - Register: \n[.hym]
  741.      Set the (right) hyphenation margin to LENGTH.  If the current
  742.      adjustment mode is not `b' or `n', the line is not hyphenated if
  743.      it is shorter than LENGTH.  Without an argument, the hyphenation
  744.      margin is reset to its default value, which is 0.  The default
  745.      scaling indicator for this request is `m'.  The hyphenation margin
  746.      is associated with the current environment (*note Environments::).
  747.  
  748.      A negative argument resets the hyphenation margin to zero, emitting
  749.      a warning of type `range'.
  750.  
  751.      The current hyphenation margin is available in the `.hym' read-only
  752.      number register.
  753.  
  754.  - Request: .hys [hyphenation_space]
  755.  - Register: \n[.hys]
  756.      Set the hyphenation space to HYPHENATION_SPACE.  If the current
  757.      adjustment mode is `b' or `n', don't hyphenate the line if it can
  758.      be justified by adding no more than HYPHENATION_SPACE extra space
  759.      to each word space.  Without argument, the hyphenation space is
  760.      set to its default value, which is 0.  The default scaling
  761.      indicator for this request is `m'.  The hyphenation space is
  762.      associated with the current environment (*note Environments::).
  763.  
  764.      A negative argument resets the hyphenation space to zero, emitting
  765.      a warning of type `range'.
  766.  
  767.      The current hyphenation space is available in the `.hys' read-only
  768.      number register.
  769.  
  770.  - Request: .shc [char]
  771.      Set the soft hyphen character to CHAR.  If the argument is
  772.      omitted, the soft hyphen character is set to the default character
  773.      `\(hy' (this is the start-up value of `gtroff' also).  The soft
  774.      hyphen character is the character that is inserted when a word is
  775.      hyphenated at a line break.  If the soft hyphen character does not
  776.      exist in the font of the character immediately preceding a
  777.      potential break point, then the line is not broken at that point.
  778.      Neither definitions (specified with the `char' request) nor
  779.      translations (specified with the `tr' request) are considered when
  780.      finding the soft hyphen character.
  781.  
  782.  - Request: .hla language
  783.  - Register: \n[.hla]
  784.      Set the current hyphenation language to the string LANGUAGE.
  785.      Hyphenation exceptions specified with the `hw' request and
  786.      hyphenation patterns specified with the `hpf' request are both
  787.      associated with the current hyphenation language.  The `hla'
  788.      request is usually invoked by the `troffrc' or the `troffrc-end'
  789.      files; `troffrc' sets the default language to `us'.
  790.  
  791.      The current hyphenation language is available as a string in the
  792.      read-only number register `.hla'.
  793.  
  794.  
  795.           .ds curr_language \n[.hla]
  796.           \*[curr_language]
  797.               => us
  798.  
  799.  
  800. 
  801. File: groff,  Node: Manipulating Spacing,  Next: Tabs and Fields,  Prev: Manipulating Hyphenation,  Up: gtroff Reference
  802.  
  803. Manipulating Spacing
  804. ====================
  805.  
  806.  - Request: .sp [distance]
  807.      Space downwards DISTANCE.  With no argument it advances 1 line.  A
  808.      negative argument causes `gtroff' to move up the page the
  809.      specified distance.  If the argument is preceded by a `|' then
  810.      `gtroff' moves that distance from the top of the page.  This
  811.      request causes a line break.  The default scaling indicator is `v'.
  812.  
  813.  - Request: .ls [nnn]
  814.  - Register: \n[.L]
  815.      Output NNN-1 blank lines after each line of text.  With no
  816.      argument, `gtroff' uses the previous value before the last `ls'
  817.      call.
  818.  
  819.  
  820.           .ls 2    \" This causes double-spaced output
  821.           .ls 3    \" This causes triple-spaced output
  822.           .ls      \" Again double spaced
  823.  
  824.      The line spacing is associated with the current environment (*note
  825.      Environments::).
  826.  
  827.      The read-only number register `.L' contains the current line
  828.      spacing setting.
  829.  
  830.  - Escape: \x'SPACING'
  831.  - Register: \n[.a]
  832.      Sometimes, extra vertical spacing is only needed occasionally, e.g.
  833.      to allow space for a tall construct (like an equation).  The `\x'
  834.      escape does this.  The escape is given a numerical argument,
  835.      usually enclosed in quotes (like `\x'3p''); the default scaling
  836.      indicator is `v'.  If this number is positive extra vertical space
  837.      is inserted below the current line.  A negative number adds space
  838.      above.  If this escape is used multiple times on the same line,
  839.      the maximum of the values is used.
  840.  
  841.      *Note Escapes::, for details on parameter delimiting characters.
  842.  
  843.      The `.a' read-only number register contains the most recent
  844.      (nonnegative) extra vertical line space.
  845.  
  846.  
  847.  - Request: .ns
  848.  - Register: \n[.ns]
  849.      Enable "no-space mode".  In this mode, spacing (either via `sp' or
  850.      via blank lines) is disabled.  The `bp' request to advance to the
  851.      next page is also disabled, except if it is accompanied by a page
  852.      number (see *Note Page Control::, for more information).  This
  853.      mode ends when actual text is output or the `rs' request is
  854.      encountered.  The read-only number register `.ns' is set to 1.
  855.  
  856.      This request is useful for macros which want to avoid that
  857.      subsequent macros inadvertently insert some vertical space before
  858.      the text starts (for example, to set up the first paragraph after
  859.      a section header).
  860.  
  861.  
  862.  - Request: .rs
  863.      Disable no-space mode.
  864.  
  865.  
  866. 
  867. File: groff,  Node: Tabs and Fields,  Next: Character Translations,  Prev: Manipulating Spacing,  Up: gtroff Reference
  868.  
  869. Tabs and Fields
  870. ===============
  871.  
  872.    A tab character (ASCII char 9, EBCDIC char 5) causes a horizontal
  873. movement to the next tab stop (much like it did on a typewriter).
  874.  
  875.  - Escape: \t
  876.      This escape is a non-interpreted tab character.  In copy mode
  877.      (*note Copy-in Mode::), `\t' is the same as a real tab character.
  878.  
  879.  - Request: .ta [n1 n2 ... nn T r1 r2 ... rn]
  880.  - Register: \n[.tabs]
  881.      Change tab stop positions.  This request takes a series of tab
  882.      specifiers as arguments (optionally divided into two groups with
  883.      the letter `T') which indicate where each tab stop is to be
  884.      (overriding any previous settings).
  885.  
  886.      Tab stops can be specified absolutely, i.e., as the distance from
  887.      the left margin.  For example, the following sets 6 tab stops every
  888.      one inch.
  889.  
  890.  
  891.           .ta 1i 2i 3i 4i 5i 6i
  892.  
  893.      Tab stops can also be specified using a leading `+' which means
  894.      that the specified tab stop is set relative to the previous tab
  895.      stop.  For example, the following is equivalent to the previous
  896.      example.
  897.  
  898.  
  899.           .ta 1i +1i +1i +1i +1i +1i
  900.  
  901.      `gtroff' supports an extended syntax to specify repeat values after
  902.      the `T' mark (these values are always taken as relative) - this is
  903.      the usual way to specify tabs set at equal intervals.  The
  904.      following is, yet again, the same as the previous examples.  It
  905.      does even more since it defines an infinite number of tab stops
  906.      separated by one inch.
  907.  
  908.  
  909.           .ta T 1i
  910.  
  911.      Now we are ready to interpret the full syntax given at the
  912.      beginning: Set tabs at positions N1, N2, ..., NN and then set tabs
  913.      at NN+R1, NN+R2, ..., NN+RN and then at NN+RN+R1, NN+RN+R2, ...,
  914.      NN+RN+RN, and so on.
  915.  
  916.      Example: `4c +6c T 3c 5c 2c' is equivalent to `4c 10c 13c 18c 20c
  917.      23c 28c 30c ...'.
  918.  
  919.      The material in each tab column (i.e., the column between two tab
  920.      stops) may be justified to the right or left or centered in the
  921.      column.  This is specified by appending `R', `L', or `C' to the tab
  922.      specifier.  The default justification is `L'.  Example:
  923.  
  924.  
  925.           .ta 1i 2iC 2iR
  926.  
  927.      Some notes:
  928.  
  929.         * The default unit of the `ta' request is `m'.
  930.  
  931.         * A tab stop is converted into a non-breakable horizontal
  932.           movement which can be neither stretched nor squeezed.  For
  933.           example,
  934.  
  935.  
  936.                .ds foo a\tb\tc
  937.                .ta T 5i
  938.                \*[foo]
  939.  
  940.           creates a single line which is a bit longer than 10 inches (a
  941.           string is used to show exactly where the tab characters are).
  942.           Now consider the following:
  943.  
  944.  
  945.                .ds bar a\tb b\tc
  946.                .ta T 5i
  947.                \*[bar]
  948.  
  949.           `gtroff' first converts the tab stops of the line into
  950.           unbreakable horizontal movements, then splits the line after
  951.           the second `b' (assuming a sufficiently short line length).
  952.           Usually, this isn't what the user wants.
  953.  
  954.         * Superfluous tabs (i.e., tab characters which do not
  955.           correspond to a tab stop) are ignored except the first one
  956.           which delimits the characters belonging to the last tab stop
  957.           for right-justifying or centering.  Consider the following
  958.           example
  959.  
  960.  
  961.                .ds Z   foo\tbar\tfoo
  962.                .ds ZZ  foo\tbar\tfoobar
  963.                .ds ZZZ foo\tbar\tfoo\tbar
  964.                .ta 2i 4iR
  965.                \*[Z]
  966.                .br
  967.                \*[ZZ]
  968.                .br
  969.                \*[ZZZ]
  970.                .br
  971.  
  972.           which produces the following output:
  973.  
  974.  
  975.                foo                 bar              foo
  976.                foo                 bar           foobar
  977.                foo                 bar              foobar
  978.  
  979.           The first line right-justifies the second `foo' relative to
  980.           the tab stop.  The second line right-justifies `foobar'.  The
  981.           third line finally right-justifies only `foo' because of the
  982.           additional tab character which marks the end of the string
  983.           belonging to the last defined tab stop.
  984.  
  985.         * Tab stops are associated with the current environment (*note
  986.           Environments::).
  987.  
  988.         * Calling `ta' without an argument removes all tab stops.
  989.  
  990.         * The start-up value of `gtroff' is `T 0.5i'.  This value is
  991.           used even for tty output devices (contrary to UNIX `nroff'
  992.           which has tab stops preset every 0.8i).
  993.  
  994.  
  995.      The read-only number register `.tabs' contains a string
  996.      representation of the current tab settings suitable for use as an
  997.      argument to the `ta' request.
  998.  
  999.  
  1000.           .ds tab-string \n[.tabs]
  1001.           \*[tab-string]
  1002.               => T120u
  1003.  
  1004.  
  1005.  - Request: .tc [fill-char]
  1006.      Normally `gtroff' fills the space to the next tab stop with
  1007.      whitespace.  This can be changed with the `tc' request.  With no
  1008.      argument `gtroff' reverts to using whitespace, which is the
  1009.      default.  The value of this "tab repetition" character is
  1010.      associated with the current environment (*note Environments::).
  1011.  
  1012. * Menu:
  1013.  
  1014. * Leaders::
  1015. * Fields::
  1016.  
  1017. 
  1018. File: groff,  Node: Leaders,  Next: Fields,  Prev: Tabs and Fields,  Up: Tabs and Fields
  1019.  
  1020. Leaders
  1021. -------
  1022.  
  1023.    Sometimes it may may be desirable to use the `tc' request to fill a
  1024. particular tab stop with a given character (for example dots in a table
  1025. of contents), but also normal tab stops on the rest of the line.  For
  1026. this `gtroff' provides an alternate tab mechanism, called "leaders"
  1027. which does just that.
  1028.  
  1029.    A leader character (character code 1) behaves similarly to a tab
  1030. character: It moves to the next tab stop.  The only difference is that
  1031. for this movement, the fill character defaults to a period character and
  1032. not to space.
  1033.  
  1034.  - Escape: \a
  1035.      This escape is a non-interpreted leader character.  In copy mode
  1036.      (*note Copy-in Mode::), `\a' is the same as a real leader
  1037.      character.
  1038.  
  1039.  - Request: .lc [fill-char]
  1040.      Declare the leader character.  Without an argument, leaders act the
  1041.      same as tabs (i.e., using whitespace for filling).  `gtroff''s
  1042.      start-up value is `.'.  The value of this "leader repetition"
  1043.      character is associated with the current environment (*note
  1044.      Environments::).
  1045.  
  1046.    For a table of contents, to name an example, tab stops may be
  1047. defined so that the section number is one tab stop, the title is the
  1048. second with the remaining space being filled with a line of dots, and
  1049. then the page number slightly separated from the dots.
  1050.  
  1051.  
  1052.      .ds entry 1.1\tFoo\a\t12
  1053.      .lc .
  1054.      .ta 1i 5i +.25i
  1055.      \*[entry]
  1056.  
  1057. This produces
  1058.  
  1059.  
  1060.      1.1  Foo..........................................  12
  1061.  
  1062. 
  1063. File: groff,  Node: Fields,  Prev: Leaders,  Up: Tabs and Fields
  1064.  
  1065. Fields
  1066. ------
  1067.  
  1068.    "Fields" are a more general way of laying out tabular data.  A field
  1069. is defined as the data between a pair of "delimiting characters".  It
  1070. contains substrings which are separated by "padding characters".  The
  1071. width of a field is the distance on the _input_ line from the position
  1072. where the field starts to the next tab stop.  A padding character
  1073. inserts stretchable space similar to TeX's `\hss' command (thus it can
  1074. even be negative) to make the sum of all substring lengths plus the
  1075. stretchable space equal to the field width.  If more than one padding
  1076. character is inserted, the available space is evenly distributed among
  1077. them.
  1078.  
  1079.  - Request: .fc [delim-char [padding-char]]
  1080.      Define a delimiting and a padding character for fields.  If the
  1081.      latter is missing, the padding character defaults to a space
  1082.      character.  If there is no argument at all, the field mechanism is
  1083.      disabled (which is the default).  Note that contrary to e.g. the
  1084.      tab repetition character, delimiting and padding characters are
  1085.      not associated to the current environment (*note Environments::).
  1086.  
  1087.      Example:
  1088.  
  1089.  
  1090.           .fc # ^
  1091.           .ta T 3i
  1092.           #foo^bar^smurf#
  1093.           .br
  1094.           #foo^^bar^smurf#
  1095.  
  1096.      and here the result:
  1097.  
  1098.  
  1099.           foo         bar          smurf
  1100.           foo            bar       smurf
  1101.  
  1102.  
  1103. 
  1104. File: groff,  Node: Character Translations,  Next: Troff and Nroff Mode,  Prev: Tabs and Fields,  Up: gtroff Reference
  1105.  
  1106. Character Translations
  1107. ======================
  1108.  
  1109.    The control character (`.') and the no-break control character (`'')
  1110. can be changed with the `cc' and `c2' requests, respectively.
  1111.  
  1112.  - Request: .cc [c]
  1113.      Set the control character to C.  With no argument the default
  1114.      control character `.' is restored.  The value of the control
  1115.      character is associated with the current environment (*note
  1116.      Environments::).
  1117.  
  1118.  - Request: .c2 [c]
  1119.      Set the no-break control character to C.  With no argument the
  1120.      default control character `'' is restored.  The value of the
  1121.      no-break control character is associated with the current
  1122.      environment (*note Environments::).
  1123.  
  1124.  - Request: .eo
  1125.      Disable the escape mechanism completely.  After executing this
  1126.      request, the backslash character `\' no longer starts an escape
  1127.      sequence.
  1128.  
  1129.      This request can be very helpful in writing macros since it is not
  1130.      necessary then to double the escape character.  Here an example:
  1131.  
  1132.  
  1133.           .\" This is a simplified version of the
  1134.           .\" .BR request from the man macro package
  1135.           .eo
  1136.           .de BR
  1137.           .  ds result \&
  1138.           .  while (\n[.$] >= 2) \{\
  1139.           .    as result \fB\$1\fR\$2
  1140.           .    shift 2
  1141.           .  \}
  1142.           .  if \n[.$] .as result \fB\$1
  1143.           \*[result]
  1144.           .  ft R
  1145.           ..
  1146.           .ec
  1147.  
  1148.  
  1149.  - Request: .ec [c]
  1150.      Set the escape character to C.  With no argument the default
  1151.      escape character `\' is restored.  It can be also used to
  1152.      re-enable the escape mechanism after an `eo' request.
  1153.  
  1154.      Note that changing the escape character globally will likely break
  1155.      macro packages since `gtroff' has no mechanism (like TeX) to
  1156.      `intern' macros, i.e., to convert a macro definition into an
  1157.      internal form which is independent of its representation.  If a
  1158.      macro is called, it is executed literally.
  1159.  
  1160.  - Escape: \e
  1161.      This escape sequence prints the current escape character (which is
  1162.      the backslash character `\' by default).
  1163.  
  1164.    A "translation" is a mapping of an input character to an output
  1165. character.  The default mappings are given in the font definition files
  1166. for the specific output device (*note Font Files::); all mappings (both
  1167. with `tr' and in the font definition files) occur at output time, i.e.,
  1168. the input character gets assigned the metric information of the mapped
  1169. output character.
  1170.  
  1171.  - Request: .tr abcd...
  1172.      Translate character A to B, character C to D, etc.  If there is an
  1173.      odd number of arguments, the last one is translated to the space
  1174.      character.
  1175.  
  1176.      Some notes:
  1177.  
  1178.         * Special characters (`\(XX', `\[XXX]', `\C'XXX'', `\'', `\`',
  1179.           `\-', `\_'), characters defined with the `char' request, and
  1180.           numbered characters (`\N'XXX'') can be translated also.
  1181.  
  1182.         * The `\e' escape can be translated also.
  1183.  
  1184.         * Characters can be mapped onto the `\%' and `\~' escapes (but
  1185.           `\%' and `\~' can't be mapped onto another character).
  1186.  
  1187.         * The following characters can't be translated: space (with one
  1188.           exception, see below), backspace, newline, leader (and `\a'),
  1189.           tab (and `\t').
  1190.  
  1191.         * Translations are not considered for finding the soft hyphen
  1192.           character set with the `shc' request.
  1193.  
  1194.         * The character pair `C\&' (this is an arbitrary character C
  1195.           followed by the zero width space character) maps this
  1196.           character to nothing.
  1197.  
  1198.  
  1199.                .tr a\&
  1200.                foo bar
  1201.                    => foo br
  1202.  
  1203.           It is even possible to map the space character to nothing:
  1204.  
  1205.  
  1206.                .tr aa \&
  1207.                foo bar
  1208.                    => foobar
  1209.  
  1210.           As shown in the example, the space character can't be the
  1211.           first character pair as an argument of `tr'.  Additionally,
  1212.           it is not possible to map the space character to any other
  1213.           character; requests like `.tr aa x' undo `.tr aa \&' instead.
  1214.  
  1215.           If justification is active, lines are justified in spite of
  1216.           the `empty' space character (but there is no minimal
  1217.           distance, i.e. the space character, between words).
  1218.  
  1219.         * After an output character has been constructed (this happens
  1220.           at the moment immediately before the character is appended to
  1221.           an output character list, either by direct output, in a
  1222.           macro, diversion, or string), it is no longer affected by
  1223.           `tr'.
  1224.  
  1225.         * Without an argument, the `tr' request is ignored.
  1226.  
  1227.  - Request: .trnt abcd...
  1228.      `trnt' is the same as the `tr' request except that the
  1229.      translations do not apply to text that is transparently throughput
  1230.      into a diversion with `\!'.  *Note Diversions::, for more
  1231.      information.
  1232.  
  1233.      For example,
  1234.  
  1235.  
  1236.           .tr ab
  1237.           .di x
  1238.           \!.tm a
  1239.           .di
  1240.           .x
  1241.  
  1242.      prints `b' to the standard error stream; if `trnt' is used instead
  1243.      of `tr' it prints `a'.
  1244.  
  1245. 
  1246. File: groff,  Node: Troff and Nroff Mode,  Next: Line Layout,  Prev: Character Translations,  Up: gtroff Reference
  1247.  
  1248. Troff and Nroff Mode
  1249. ====================
  1250.  
  1251.    Originally, `nroff' and `troff' were two separate programs, the
  1252. former for tty output, the latter for everything else.  With GNU
  1253. `troff', both programs are merged into one executable, sending its
  1254. output to a device driver (`grotty' for tty devices, `grops' for
  1255. POSTSCRIPT, etc.) which interprets the intermediate output of `gtroff'.
  1256. For UNIX `troff' it makes sense to talk about "Nroff mode" and "Troff
  1257. mode" since the differences are hardcoded.  For GNU `troff', this
  1258. distinction is not appropriate because `gtroff' simply takes the
  1259. information given in the font files for a particular device without
  1260. handling requests specially if a tty output device is used.
  1261.  
  1262.    Usually, a macro package can be used with all output devices.
  1263. Nevertheless, it is sometimes necessary to make a distinction between
  1264. tty and non-tty devices: `gtroff' provides two built-in conditions `n'
  1265. and `t' for the `if', `ie', and `while' requests to decide whether
  1266. `gtroff' shall behave like `nroff' or like `troff'.
  1267.  
  1268.  - Request: .troff
  1269.      Make the `t' built-in condition true (and the `n' built-in
  1270.      condition false) for `if', `ie', and `while' conditional requests.
  1271.      This is the default if `gtroff' (_not_ `groff') is started with
  1272.      the `-R' switch to avoid loading of the start-up files `troffrc'
  1273.      and `troffrc-end'.  Without `-R', `gtroff' stays in troff mode if
  1274.      the output device is not a tty (e.g. `ps').
  1275.  
  1276.  - Request: .nroff
  1277.      Make the `n' built-in condition true (and the `t' built-in
  1278.      condition false) for `if', `ie', and `while' conditional requests.
  1279.      This is the default if `gtroff' uses a tty output device; the
  1280.      code for switching to nroff mode is in the file `tty.tmac' which
  1281.      is loaded by the start-up file `troffrc'.
  1282.  
  1283.    *Note Conditionals and Loops::, for more details on built-in
  1284. conditions.
  1285.  
  1286.    For tty output devices, underlining is done by emitting sequences of
  1287. `_' and `\b' (the backspace character) before the actual character.
  1288. Literally, this is printing an underline character, then moving back
  1289. one character position, and printing the actual character at the same
  1290. position as the underline character (similar to a typewriter).
  1291. Usually, a modern terminal can't interpret this (and the original
  1292. Teletype machines for which this sequence was appropriate are no longer
  1293. in use).  You need a pager program like `less' which translates this
  1294. into ISO 6429 SGR sequences to control terminals.
  1295.  
  1296. 
  1297. File: groff,  Node: Line Layout,  Next: Page Layout,  Prev: Troff and Nroff Mode,  Up: gtroff Reference
  1298.  
  1299. Line Layout
  1300. ===========
  1301.  
  1302.    The following drawing shows the dimensions which `gtroff' uses for
  1303. placing a line of output onto the page.  They are labeled with the
  1304. request which manipulates each dimension.
  1305.  
  1306.  
  1307.                      -->| in |<--
  1308.                         |<-----------ll------------>|
  1309.                    +----+----+----------------------+----+
  1310.                    |    :    :                      :    |
  1311.                    +----+----+----------------------+----+
  1312.                 -->| po |<--
  1313.                    |<--------paper width---------------->|
  1314.  
  1315. These dimensions are:
  1316.  
  1317. `po'
  1318.      "Page offset" - this is the leftmost position of text on the final
  1319.      output, defining the "left margin".
  1320.  
  1321. `in'
  1322.      "Indentation" - this is the distance from the left margin where
  1323.      text is printed.
  1324.  
  1325. `ll'
  1326.      "Line length" - this is the distance from the left margin to right
  1327.      margin.
  1328.  
  1329.  
  1330.      .in +.5i
  1331.      .ll -.5i
  1332.      A bunch of really boring text which should
  1333.      be indented from both margins.
  1334.      Replace me with a better (and more) example!
  1335.      .in -.5i
  1336.      .ll +.5i
  1337.  
  1338.  - Request: .po [offset]
  1339.  - Request: .po +offset
  1340.  - Request: .po -offset
  1341.  - Register: \n[.o]
  1342.      Set horizontal page offset to OFFSET (or increment or decrement
  1343.      the current value by OFFSET).  Note that this request does not
  1344.      cause a break, so changing the page offset in the middle of text
  1345.      being filled may not yield the expected result.  The initial value
  1346.      is 1i.  For tty output devices, it is set to 0 in the startup file
  1347.      `troffrc'; the default scaling indicator is `m' (and not `v' as
  1348.      incorrectly documented in the original UNIX troff manual).
  1349.  
  1350.      The current page offset can be found in the read-only number
  1351.      register `.o'.
  1352.  
  1353.      If `po' is called without an argument, the page offset is reset to
  1354.      the previous value before the last call to `po'.
  1355.  
  1356.  
  1357.           .po 3i
  1358.           \n[.o]
  1359.               => 720
  1360.           .po -1i
  1361.           \n[.o]
  1362.               => 480
  1363.           .po
  1364.           \n[.o]
  1365.               => 720
  1366.  
  1367.  
  1368.  - Request: .in [indent]
  1369.  - Request: .in +indent
  1370.  - Request: .in -indent
  1371.  - Register: \n[.i]
  1372.      Set indentation to INDENT (or increment or decrement the current
  1373.      value by INDENT).  This request causes a break.  Initially, there
  1374.      is no indentation.
  1375.  
  1376.      If `in' is called without an argument, the indentation is reset to
  1377.      the previous value before the last call to `in'.  The default
  1378.      scaling indicator is `m'.
  1379.  
  1380.      The indentation is associated with the current environment.
  1381.  
  1382.      If a negative indentation value is specified (which is not
  1383.      allowed), `gtroff' emits a warning of type `range' and sets the
  1384.      indentation to zero.
  1385.  
  1386.      The effect of `in' is delayed until a partially collected line (if
  1387.      it exists) is output.  A temporary indent value is reset to zero
  1388.      also.
  1389.  
  1390.      The current indentation (as set by `in') can be found in the
  1391.      read-only number register `.i'.
  1392.  
  1393.  - Request: .ti offset
  1394.  - Request: .ti +offset
  1395.  - Request: .ti -offset
  1396.  - Register: \n[.in]
  1397.      Temporarily indent the next output line by OFFSET.  If an
  1398.      increment or decrement value is specified, adjust the temporary
  1399.      indentation relative to the value set by the `in' request.
  1400.  
  1401.      This request causes a break; its value is associated with the
  1402.      current environment.  The default scaling indicator is `m'.  A call
  1403.      of `ti' without an argument is ignored.
  1404.  
  1405.      If the total indentation value is negative (which is not allowed),
  1406.      `gtroff' emits a warning of type `range' and sets the temporary
  1407.      indentation to zero.  `Total indentation' is either OFFSET if
  1408.      specified as an absolute value, or the temporary plus normal
  1409.      indentation, if OFFSET is given as a relative value.
  1410.  
  1411.      The effect of `ti' is delayed until a partially collected line (if
  1412.      it exists) is output.
  1413.  
  1414.      The read-only number register `.in' is the indentation that applies
  1415.      to the current output line.
  1416.  
  1417.      The difference between `.i' and `.in' is that the latter takes
  1418.      into account whether a partially collected line still uses the old
  1419.      indentation value or a temporary indentation value is active.
  1420.  
  1421.  - Request: .ll [length]
  1422.  - Request: .ll +length
  1423.  - Request: .ll -length
  1424.  - Register: \n[.l]
  1425.  - Register: \n[.ll]
  1426.      Set the line length to LENGTH (or increment or decrement the
  1427.      current value by LENGTH).  Initially, the line length is set to
  1428.      6.5i.  The effect of `ll' is delayed until a partially collected
  1429.      line (if it exists) is output.  The default scaling indicator
  1430.      is `m'.
  1431.  
  1432.      If `ll' is called without an argument, the line length is reset to
  1433.      the previous value before the last call to `ll'.  If a negative
  1434.      line length is specified (which is not allowed), `gtroff' emits a
  1435.      warning of type `range' and sets the line length to zero.
  1436.  
  1437.      The line length is associated with the current environment.
  1438.  
  1439.      The current line length (as set by `ll') can be found in the
  1440.      read-only number register `.l'.  The read-only number register
  1441.      `.ll' is the line length that applies to the current output line.
  1442.  
  1443.      Similar to `.i' and `.in', the difference between `.l' and `.ll'
  1444.      is that the latter takes into account whether a partially
  1445.      collected line still uses the old line length value.
  1446.  
  1447.